home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / scope / 051-075 / scopedisk68 / funckey / funckey.doc < prev    next >
Text File  |  1995-03-19  |  12KB  |  286 lines
  1.  
  2.                /*****************************************\
  3.                 *>                                     <*
  4.                 *>   The FuncKey Function Key Editor   <*
  5.                 *>             Version 1.01            <*
  6.                 *>   Copyright (c) 1987 by Anson Mah   <*
  7.                 *>                                     <*
  8.                \*****************************************/
  9.  
  10.                 This document must accompany the program.
  11.                   A completely distributable bundle is:
  12.                                FuncKey
  13.                                FuncKey.info
  14.                                Fhandler
  15.                                FuncKey.doc
  16.  
  17. ------------
  18. INTRODUCTION
  19. ------------
  20.  
  21.      FuncKey*  is a shareware  program  developed for the Amiga^.   A fee of
  22. $5 (five) is requested.  Commented source, in addition to the executable, is
  23. available for $10.  The source code will be supplied on disk, and purchasers
  24. of the  source  will  be entitled  to one  free  upgrade to both  source and
  25. executable  when or if another  version of  FuncKey is written.   When or if
  26. will be  determined  by the level of  response to  Version 1.00  of FuncKey.
  27. Please send payments and/or comments to the address below.
  28.  
  29.      FuncKey is  a tool that  will put an  end to the uselessness of the ten
  30. function keys sitting atop the Amiga keyboard.  This 'hotkey' utility allows
  31. each  function  key to be  programmed  with  up to five  different  keyboard
  32. equivalent  strings,  each string  able to hold up  to 79 characters and may
  33. contain control/escape sequences as well as left- and right-Amiga sequences.
  34. The five possible strings are accessed by combinations of Shift,  Alternate,
  35. Left-/Right-Amiga, and the function keys.
  36.  
  37.      Please note that FuncKey requires at least version 1.2 of AmigaDOS.
  38.  
  39.  
  40. ----------------
  41. STARTING FuncKey
  42. ----------------
  43.  
  44.      It is very important that the file called  Fhandler be placed in either
  45. the  c: directory or the  "current" directory.   If used from CLI, "current"
  46. refers to the  directory  that has been  CD'ed to  before executing FuncKey.
  47. If  used  from Workbench,  "current" refers to the  directory in  which  the
  48. FuncKey program lies.
  49.  
  50.      FuncKey may be started from  either the CLI (Command Line Interface) or
  51. Workbench.  From CLI, the syntax is
  52.  
  53.      [run] FuncKey [filename]
  54.  
  55. That is, the program may be started by simply entering  'FuncKey' or started
  56. as a background task by entering 'run FuncKey'.  In these cases, the FuncKey
  57. Control Panel will  appear, allowing the function keys to be programmed.  In
  58. addition, the filename of a FuncKey data file may be  entered on the command
  59. line.   This will initialize  the function keys with pre-recorded data,  and
  60. the  Control Panel  will not be brought up.   More on this  particular topic
  61. will be presented later.
  62.  
  63.      From  Workbench,  FuncKey  may  be  started  by  double-clicking on the
  64. FuncKey icon  (shaped like a function key) or a  FuncKey data file icon.  In
  65. the first case,  the Control Panel will appear,  and in the second case, the
  66. function keys will have been programmed, so the Control Panel is not needed.
  67.  
  68.  
  69. -----------------------------
  70. USING FuncKey - CONTROL PANEL
  71. -----------------------------
  72.  
  73.      The  FuncKey Control Panel will  appear only  under the following three
  74. conditions:
  75.  
  76.      1> FuncKey is started in CLI with 'FuncKey', 'run FuncKey'
  77.      2> FuncKey is started with the the FuncKey icon in Workbench
  78.      3> RIGHT-Alt-HELP is depressed and the Control Panel is resident
  79.  
  80. An explanation of the Control Panel follow.  It assumes the knowledge of the
  81. terms 'gadget' and 'string gadget'.
  82.  
  83. String Gadgets F1 to F10:
  84.      The gadgets hold the definitions of the function keys.  Each definition
  85.      may be up  to 79 characters  in length.   Control and left-/right-Amiga
  86.      keys are specified by  preceding the character  desired with one of the
  87.      following three characters:
  88.         ^  (caret)       introduces a control character ( eg ^m is CTRL-m )
  89.         {  (left brace)  introduces a left-Amiga sequence ( eg {m )
  90.         }  (right brace) introduces a right-Amiga sequence ( eg }q )
  91.      The  characters  ^ { }  can  be  generated  in a  definition  simply by
  92.      entering two of them consecutively.  For example {{ will result in a {.
  93.      Thus  the  sequences control-^, left-Amiga-{, and right-Amiga-} are not
  94.      possible.   (Any actual control characters  [represented by a small box
  95.      in the string gadget] will not be acknowledged.)
  96.  
  97. Key Qualifiers:
  98.      There are five gadgets labelled None, Shft, ALT, LAmi, RAmi.  These are
  99.      used to  select  which  particular set of  the possible  five are being
  100.      displayed  and edited.   For instance, to work with the  definitions of
  101.      the ten ALT-<function key> combinations, choose ALT.
  102.  
  103. Filename String Gadget:
  104.      A file can be  specified in which to  store or  from which  to retrieve
  105.      FuncKey  definitions.   The name of the  file is placed in this gadget. 
  106.      The default filename is s:func.key.
  107.  
  108. Load & Save Gadgets:
  109.      These are  used to load or save  function key  data from or to the file
  110.      specified in the filename string gadget.
  111.  
  112. I (Icon) Gadget:
  113.      This  gadget is used  in conjunction  with  the save feature.  If it is
  114.      selected, an icon will be created for the data file.  This icon, in the
  115.      Default Tool field,  points to the  FuncKey Control Panel  program with
  116.      ':FuncKey' as a default,  which specfies the root directory of the disk
  117.      that the data file icon is on.  This may be  changed with the Workbench
  118.      function Info.  (see the manual "Introduction to Amiga")
  119.      The  gadget  defaults  to an on  position if  FuncKey is  started  from
  120.      Workbench and to an off position if started from CLI.
  121.  
  122. Resident YES & NO Gadgets:
  123.      The Control Panel  may be kept  active in  memory  and be available for
  124.      instant recall.  To be sure that it is active, the YES gadget should be
  125.      chosen.  To have it terminate (and thus free some memory when it is not
  126.      in use), select  the NO gadget.   The default  is YES  when the Control
  127.      Panel is executed with 'run FuncKey' and  'run FuncKey <filename>' from
  128.      CLI and  when started  with the selection of a  data file icon from the
  129.      Workbench.   To recall the Control Panel if it is off but resident, use
  130.      the key sequence Right-Alt-HELP.
  131.  
  132. FuncKey ON & OFF Gadgets:
  133.      These  gadgets  allow  the  setting  of the  state of the  function key
  134.      handler  process.   If the  handler  is to be turned on,  choose the ON
  135.      gadget, otherwise choose the OFF gadget.  The default setting is ON.
  136.  
  137. Clear Gadget:
  138.      Selecting this will clear the Control Panel of all definitions.
  139.  
  140. Fetch Gadget:
  141.      This  fetches  the  definitions  currently  contained  in  the  handler
  142.      process.   This  is  useful if a  bad  edit  is  performed,  such as an
  143.      involuntary  Clear  of the  Control Panel.   Fetch will also return the
  144.      state  of the  handler,  and will adjust  the  FuncKey  ON/OFF  gadgets
  145.      accordingly.
  146.  
  147. Cancel Gadget:
  148.      Selecting  this  will cancel any  edits taken  place in a  function key
  149.      editing session.   All changes  made will not take place.   Cancel will
  150.      close the  Control Panel window  and will  remove it from memory if the
  151.      Resident NO gadget is selected.
  152.  
  153. <USE> Gadget:
  154.      When all  edits are  satisfactory,  choosing this will send the data to
  155.      the handler process and exit the Control Panel.  The Control Panel will
  156.      be removed from memory if the Resident NO gadget is selected.
  157.  
  158. <KILL> Gadget:
  159.      True to its name, the KILL function will terminate both the handler and
  160.      Control Panel processes, removing them from memory.
  161.  
  162.      If any  errors  occur  during any  Control Panel  functions,  a message
  163. describing the error will appear in the window title strip for approximately
  164. one second.
  165.  
  166.  
  167. ------------------------------------
  168. USING FuncKey - FUNCTION KEY HANDLER
  169. ------------------------------------
  170.  
  171.      As  stated earlier,  the handler  program  Fhandler  must be  placed in
  172. either the  c: or current directory.   Fhandler cannot be executed by itself
  173. (a crash, aka a Guru Meditation, will result!).
  174.  
  175.      The handler process stays  resident in memory until it is KILLed by the
  176. Control Panel.   It may be toggled on and off by Right-Amiga-HELP.  However,
  177. if the Control Panel is resident also,  the sequence will bring the Panel up
  178. and toggling the state of the handler is performed on it instead.
  179.  
  180.      FuncKey Version 1.01  will also  pass through a key  press to the Amiga
  181. if a  function  key sequence  has  not  been defined.   For example,  if the
  182. handler is active, and F7 has not been defined with FuncKey, the F7 keypress
  183. is passed to the Amiga input stream untouched.   Thus with a program such as
  184. Scribble~,  which makes use of function keys, an undefined F7 will result in
  185. Scribble  toggling  underline  mode  on and off.   If F7 is instead defined,
  186. turning the handler  off is the only  way to make use of Scribble's  (or any
  187. other program's) function keys.
  188.  
  189.  
  190. -------------------------
  191. RECOMMENDED CONFIGURATION
  192. -------------------------
  193.  
  194.      A recommended  FuncKey  environment is to  have the Fhandler program in
  195. the c:  directory and a call to FuncKey in the startup-sequence.   If a data
  196. file  is  often  used,  the  best  way  to  invoke  FuncKey  is  by  issuing
  197.  
  198.      FuncKey <filename>
  199.  
  200. from the  startup-sequence.   This will load up the handler,  initialize it,
  201. and remove the Control Panel, minimizing the use of memory.
  202.  
  203.  
  204. --------------------------------------
  205. POSSIBLE PROBLEMS & SOLUTIONS FOR THEM
  206. --------------------------------------
  207.  
  208. Prob - Function keys are not responding!
  209. Soln - The key may not be defined, so check the Control Panel.
  210.      - The handler may  be  in the off state,  so press  Right-Amiga-HELP to
  211.        toggle it.
  212.  
  213. Prob - Function key doesn't produce the right result!
  214. Soln - The key may be defined with FuncKey and also used for another purpose
  215.        by another program.   Either turn the handler off  (with Right-Amiga-
  216.        HELP) or clear that key's definition from FuncKey, which will let the
  217.        Amiga see the key when the handler is active.
  218.  
  219. Prob - Selecting the data file icon doesn't seem to result in any actions!
  220. Soln - If all is proper,  the handler will have been loaded and initialized,
  221.        and trying out the function keys will show that.
  222.      - If a Workbench error occurs, it may be that the FuncKey Control Panel
  223.        program is in a  location other  than the root directory of the disk.
  224.        A change via the Workbench Info is in order.
  225.  
  226. Prob - (actually a bug)   24 bytes are lost every time the Control Panel and
  227.        the handler are terminated (KILLed).
  228. Soln - Gotta find a fix for it!
  229.  
  230.  
  231. -------------------
  232. REFERENCE (CUT-OUT)
  233. -------------------
  234. -----8<-----cut here-----8<-----cut here-----8<-----cut here-----8<-----
  235.  
  236.  
  237. -----------------------------
  238. FuncKey Reference Information
  239. -----------------------------
  240.  
  241. Usage:  [run] FuncKey [filename]
  242.  
  243. Recalling Control Panel:  Right-Alt-HELP
  244.  
  245. Toggle state of function key handler:  Right-Alt-HELP
  246. (used when the Control Panel is not active)
  247.  
  248. Examples of definitions:
  249.      dir^m --> results in 'dir' followed by a carriage return
  250.      ^x    --> results in CTRL-x (clears the CLI command line)
  251.      ^c    --> results in CTRL-c (defines a BREAK key)
  252.      list  --> results in 'list'
  253.      {m    --> results in Left-Amiga-m
  254.      }q    --> results in Right-Amiga-q
  255.  
  256. REMINDER: Fhandler must be in either the c: or current directory.
  257.  
  258.  
  259. -----8<-----cut here-----8<-----cut here-----8<-----cut here-----8<-----
  260.  
  261.  
  262. --------------------
  263. AUTHOR'S ADDRESS(ES)
  264. --------------------
  265. Post (zzzz):   Anson Mah
  266.                2735 E. 2nd Ave.
  267.                Vancouver, B.C.
  268.                Canada  V5M 1E2
  269. Phone:         (604) 254-6849
  270.  
  271. uucp: (before Sept '87)   {anywhere}!ubc-vision!mdivax1!amah
  272.                                                    OR  \
  273.                                                         mdisun11!amah
  274.       (after Sept '87)    {anywhere}!ubc-vision!ubc-bdcvax!mah
  275.  
  276. Bitnet:   USERAMAH@UBCMTSG
  277.  
  278.  
  279. -----
  280. NOTES
  281. -------------------------------------------------------------------------
  282. *  FuncKey is Copyright (c) 1987 Anson Mah
  283. ~  Scribble! Copyright (c) 1986 Micro-Systems Software, Inc.
  284. ^  Amiga is a registered trademark of Commodore Business Machines, Ltd.
  285. -------------------------------------------------------------------------
  286.